[kotlin][client] Register enumUnknownDefaultCase as a CliOption so it appears in config-help and the docs - #24977

enumUnknownDefaultCase has worked for the kotlin generator since it shipped in v5.3.1, but it is advertised nowhere. It appears in neither config-help -g kotlin nor docs/generators/kotlin.md, so the only way to find out it exists is to read the generator source. In practice users conclude the kotlin client does not support enum fallbacks at all.

It is not a documentation oversight that can be fixed in the docs. docs/generators/*.md is generated from each generator's CliOption list by bin/utils/export_generator.sh (config-help --full-details --format markdown), and bin/utils/ensure-up-to-date re-runs it as a CI gate. The missing config-help entry and the missing docs row are the same bug, and registering the option fixes both.

Root cause

AbstractKotlinCodegen calls cliOptions.clear() at AbstractKotlinCodegen.java:308 and then re-adds only the Kotlin-specific options. That discards the registration DefaultCodegen makes at DefaultCodegen.java:2190-2199. DefaultCodegen.processOpts() still reads the key back out of additionalProperties at DefaultCodegen.java:449, which is why the flag has always been functional — just invisible. Passing --additional-properties=enumUnknownDefaultCase=true today produces a correct client; nothing tells you that you can.

The clear() predates the option by nearly four years — it was introduced in 7cad47dd399 (2018-01-27, "[kotlin-server] --library=ktor"), and enumUnknownDefaultCase landed in c305c717156 (2021-12-21, #11078). Kotlin was never deliberately excluded.

Why KotlinClientCodegen and not AbstractKotlinCodegen

kotlin is the only Kotlin generator whose templates implement the fallback. Grepping the template directories for enumUnknownDefaultCase / unknown_default_open_api gives 11 files under kotlin-client and zero under kotlin-spring, kotlin-server, kotlin-vertx-server, kotlin-misk, kotlin-wiremock and ktorm-schema.

Registering it on the abstract class would advertise it on generators where enabling it makes the output worse rather than better. The extra enum constant is injected language-neutrally in DefaultCodegen (injectEnumUnknownDefaultCase), so kotlin-spring with the flag on emits an unknown_default_open_api constant into the model's public API while forValue() still throws IllegalArgumentException on an unknown value — a phantom constant and the original crash.

This mirrors GoClientCodegen.java:167-177, which re-registers this same option after AbstractGoCodegen's own cliOptions.clear(); docs/generators/go.md has the row and the other Go generators do not.

Serialization-library support is partial, and the description says so

Support is partial in ways that are easy to get wrong, so the description names each gap rather than implying blanket support:

Add an unknown_default_open_api enum case as a fallback for unrecognized values. Only moshi(serializationLibrary) decodes every unknown value to it: jackson skips nullable enums, kotlinx_serialization skips non-string enums, and neither gson(serializationLibrary) nor multiplatform(library) decodes to it at all.

For reference, where each stands in the kotlin-client templates today:

• moshi — full. SerializerHelper.kt registers EnumJsonAdapter.create(...).withUnknownFallback(...) for every enum, wired in from Serializer.kt.mustache.
• jackson — non-nullable enums only. enum_class.mustache gates the decode() fallback on {{^isNullable}}; a nullable enum falls through to entries.firstOrNull { ... } and yields null. Because decode() carries @JsonCreator, Jackson routes through it and never reaches the @JsonEnumDefaultValue / READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE path that Serializer.kt.mustache sets up.
• kotlinx_serialization — string enums only. The generated KSerializer emits the ?: <fallback> under {{#isString}} and ?: throw IllegalArgumentException("Unknown enum value: $value") under {{^isString}}, so an integer enum still throws. (Inline enums via data_class.mustache do fall back unconditionally.)
• gson — none. No enum adapter is registered, so Gson's built-in returns null for an unrecognized name. Quieter than throwing, and arguably worse: null is indistinguishable from an absent field, and Gson bypasses Kotlin null checks.
• multiplatform (a library, not a serializationLibrary) — none; the serializer throws.

The phrasing follows the neighbouring options in the same file, generateOneOfAnyOfWrappers and useJackson3, which scope themselves the same way.

Related

• Closes nothing outright, but this is the discoverability half of [REQ] [kotlin-client] Support Enum Fallback Values #12970 ("[REQ] [kotlin-client] Support Enum Fallback Values"), open since 2022-07-21 with several community +1s and no maintainer response. The issue's core complaint is that the option is undocumented for kotlin, which is exactly this.
• [kotlin] fix: enumUnknownDefaultCase's moshi fallback adapters break nullable enum fields #24894 is the other half. SerializerHelper.kt.mustache emits EnumJsonAdapter.create(...) without .nullSafe(), and because that adapter shadows Moshi's null-safe built-in for every enum in the spec, any model with an optional enum property throws on encode (NullPointerException: value was null! Wrap in .nullSafe()) and on decoding an explicit JSON null. Since every property absent from required is a nullable enum, that is most models. Making the option discoverable is worth considerably more once [kotlin] fix: enumUnknownDefaultCase's moshi fallback adapters break nullable enum fields #24894 lands — together they turn a hidden, moshi-fragile flag into a feature users can actually find and rely on. The two changes touch disjoint files and neither needs to rebase on the other.

Scope and verification

One source file, one new test, and the regenerated docs/generators/kotlin.md (+1 line). No behaviour change: the default stays false and DefaultCodegen already initialised the field.

• Docs regenerated with the repo tooling, not by hand. Ran all four scripts that bin/utils/ensure-up-to-date invokes (bin/meta-codegen.sh, bin/utils/export_docs_generators.sh, bin/utils/copy-to-website.sh, bin/utils/export_generators_readme.sh); export_docs_generators.sh regenerates every generator's doc and kotlin.md was the only one that moved.
• Samples: regenerated all 128 bin/configs/kotlin*.yaml and bin/configs/ktorm*.yaml. git status --porcelain samples/ is empty.
• config-help -g kotlin from a jar built on this branch now lists the option with the description and both enum values.
• Added KotlinClientCodegenModelTest#testEnumUnknownDefaultCaseIsRegisteredAsCliOption, a regression guard for the registration itself. Verified it discriminates: with the registration reverted it fails with enumUnknownDefaultCase is not registered.
• Tests: 1430 run, 0 failures — the whole org.openapitools.codegen.kotlin package (KotlinClientCodegenModelTest, KotlinClientCodegenApiTest, AbstractKotlinCodegenTest, the misk/server/spring/vertx tests) plus AllGeneratorsTest, which includes the noDuplicateCliOptions guard. Nothing asserts an exact option count, and KotlinMiskServerCodegenOptionsTest is unaffected because the registration is scoped to kotlin rather than the abstract class.

Note for maintainers

Five other DefaultCodegen options are dropped the same way for every Kotlin generator: ensureUniqueParams, allowUnicodeIdentifiers, prependFormOrBodyParameters, legacyDiscriminatorBehavior and disallowAdditionalPropertiesIfNotPresent. I have deliberately left those alone — each needs its own check of whether the Kotlin templates honour it, and a couple are behaviour-bearing. Happy to follow up separately if that is wanted.

PR checklist

• Read the contribution guidelines.
• Built the project and regenerated docs and samples. Specifically: ./mvnw clean package; all four scripts that bin/utils/ensure-up-to-date invokes (bin/meta-codegen.sh, bin/utils/export_docs_generators.sh, bin/utils/copy-to-website.sh, bin/utils/export_generators_readme.sh); and ./bin/generate-samples.sh over all 128 bin/configs/kotlin*.yaml and bin/configs/ktorm*.yaml. git status --porcelain samples/ is empty, and kotlin.md was the only generator doc that moved. I scoped sample regeneration to Kotlin rather than every language, since the change is confined to KotlinClientCodegen's constructor — happy to run the full sweep if CI disagrees.
• @mentioning the Kotlin technical committee: @jimschubert, @andrewemery, @stefankoppier.

@jimschubert — flagging you specifically since 7cad47dd399 is where the cliOptions.clear() came from. Nothing about this change suggests that was wrong; the option simply did not exist yet, and nothing has re-added it since.

🤖 Generated with Claude Code

Summary by cubic

Registers the enumUnknownDefaultCase option for the kotlin client generator so it appears in config-help and docs/generators/kotlin.md. The flag has worked since v5.3.1 but was invisible because AbstractKotlinCodegen clears the option list, dropping DefaultCodegen's registration; no behavior changes, the default stays false.

• Registration is scoped to KotlinClientCodegen, the only Kotlin generator whose templates implement the fallback.
• Only moshi decodes every unknown value: jackson skips nullable enums, kotlinx_serialization skips non-string enums, and gson and multiplatform emit the case but don't decode to it.
• A regression test guards the registration so the option cannot silently vanish again.
• docs/generators/kotlin.md was regenerated with the repo tooling; no sample changes.

^{Written for commit fed2b66. Summary will update on new commits.}